﻿// --------------------------------------------------------------------------------------------------------------------
// <copyright file="IDownloadFiles.cs" company="XamlNinja">
//   2011 Richard Griffin and Ollie Riches
// </copyright>
// <summary>
//   IDownloadFiles.cs
// </summary>
// --------------------------------------------------------------------------------------------------------------------

namespace WP7Contrib.Services.DownloadManager
{
    using System;
    using Collections;
    using Communications;

    /// <summary>
    /// Defines the interface for the download service.
    /// </summary>
    public interface IDownloadService : IDisposable
    {
        // Downloader state changed event...
        event EventHandler<DownloaderStateEventArgs> DownloadStateChanged;

        // Download events...
        event EventHandler<FileRequestEventArgs> DownloadStarted;
        event EventHandler<FileRequestEventArgs> DownloadUpdated;
        event EventHandler<FileRequestEventArgs> DownloadStopped;
        event EventHandler<FileRequestEventArgs> DownloadFailed;
        event EventHandler<FileRequestEventArgs> DownloadCompleted;

        /// <summary>
        /// Block size used for resumable downloads.
        /// </summary>
        int BlockSize { get; }

        /// <summary>
        /// The currently queued download requests, they are processed using a FIFO strategy.
        /// </summary>
        ReadOnlyObservableCollection<FileRequest> Requests { get; }

        /// <summary>
        /// The currently supported network types.
        /// </summary>
        ReadOnlyObservableCollection<NetworkType> NetworkTypes { get; }

        /// <summary>
        /// The current network type.
        /// </summary>
        NetworkType NetworkType { get; }

        /// <summary>
        /// The state of the downloader - is it processing, paused etc..
        /// </summary>
        DownloaderState State { get; }

        /// <summary>
        /// Settings for the downloader
        /// </summary>
        ISettings Settings { get; }

        /// <summary>
        /// Starts the downloader and waits for file download requests.
        /// </summary>
        /// <returns></returns>
        IDownloadService Start();

        /// <summary>
        /// Stops the downloader and waits for file download requests.
        /// </summary>
        IDownloadService Stop();

        /// <summary>
        /// Adds a file download request, if the downloader is currently processing a request then this is queued.
        /// If the downloader is paused it is woken up and the request will be processed.
        /// </summary>
        /// <param name="url">The url for the file.</param>
        /// <param name="filePath">The local file location where the file will be downloaded to.</param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService Add(string url, string filePath);

        /// <summary>
        /// Adds a file download request, if the downloader is currently processing a request then this is queued.
        /// If the downloader is paused it is woken up and the request will be processed.
        /// </summary>
        /// <param name="url">The url for the file.</param>
        /// <param name="filePath">The local file location where the file will be downloaded to.</param>
        /// <param name="request">The created file request.</param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService Add(string url, string filePath, ref FileRequest request);

        /// <summary>
        /// Prioritise the file download request, if another download is being processed it is stopped and this request is started.
        /// </summary>
        /// <param name="url">The url for the file.</param>
        /// <param name="filePath">The local file location where the file will be downloaded to.</param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService PriorityAdd(string url, string filePath);

        /// <param name="url">The url for the file.</param>
        /// <summary>
        /// Prioritise the file download request, if another download is being processed it is stopped and this request is started.
        /// </summary>
        /// <param name="filePath">The local file location where the file will be downloaded to.</param>
        /// <param name="request">The created file request.</param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService PriorityAdd(string url, string filePath, ref FileRequest request);

        /// <summary>
        /// Prioritise an existing file download request.
        /// </summary>
        /// <param name="request">The existing file request.</param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService Prioritise(FileRequest request);

        /// <summary>
        /// Remmoves the file download request, if the download is being processed it is stopped and temporary files are deleted.
        /// </summary>
        /// <param name="request">The file request.</param>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService Remove(FileRequest request);

        /// <summary>
        /// Remmoves all the file download requests, if any downloads are or have been processed any temporary files are deleted.
        /// </summary>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService RemoveAll();

        /// <summary>
        /// Removes all failed file donload requests.
        /// </summary>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService RemoveFailed();

        /// <summary>
        /// Removes all completed file donload requests.
        /// </summary>
        /// <returns>
        /// Returns the instance of the interface - fluent interface style.
        /// </returns>
        IDownloadService RemoveCompleted();
    }
}
